IRIX Base Documentation 1998 November/IRIX 6.5.2 Base Documentation November 1998.img/usr/share/catman/p_man/cat3/lio_listio.z/lio_listio

Text File | 1998-10-20 | 15KB | 199 lines

LLLLIIIIOOOO____LLLLIIIISSSSTTTTIIIIOOOO((((3333))))                                                    LLLLIIIIOOOO____LLLLIIIISSSSTTTTIIIIOOOO((((3333))))



NNNNAAAAMMMMEEEE
     lio_listio, lio_listio64 - linked asynchronous I/O operations

CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     ####iiiinnnncccclllluuuuddddeeee <<<<aaaaiiiioooo....hhhh>>>>

     iiiinnnntttt lllliiiioooo____lllliiiissssttttiiiioooo((((iiiinnnntttt mmmmooooddddeeee,,,, aaaaiiiiooooccccbbbb____tttt **** ccccoooonnnnsssstttt lllliiiisssstttt[[[[]]]],,,, iiiinnnntttt nnnneeeennnntttt,,,, ssssiiiiggggeeeevvvveeeennnntttt____tttt ****ssssiiiigggg))));;;;

     iiiinnnntttt lllliiiioooo____lllliiiissssttttiiiioooo66664444((((iiiinnnntttt mmmmooooddddeeee,,,, aaaaiiiiooooccccbbbb66664444____tttt **** ccccoooonnnnsssstttt lllliiiisssstttt[[[[]]]],,,, iiiinnnntttt nnnneeeennnntttt,,,, ssssiiiiggggeeeevvvveeeennnntttt____tttt ****ssssiiiigggg))));;;;

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     The lllliiiioooo____lllliiiissssttttiiiioooo function allows the calling process to initiate a list of
     I/O requests with a single function call.

     The lllliiiioooo____lllliiiissssttttiiiioooo66664444() function is identical to lllliiiioooo____lllliiiissssttttiiiioooo() except that it
     takes an  array of aaaaiiiiooooccccbbbb66664444____tttt * (see <_a_i_o._h>).  This structure allows for
     the specification of a file offset greater than 2 Gigabytes.

     The mmmmooooddddeeee argument takes a value of either LIO_WAIT or LIO_NOWAIT and
     determines whether the function returns when the I/O operations have been
     completed, or as soon as the operations have been queued. If the mmmmooooddddeeee
     argument is LIO_WAIT, the function waits until all I/O is complete and
     the ssssiiiigggg argument is ignored.

     If the mmmmooooddddeeee argument is LIO_NOWAIT, the function returns immediately, and
     signal delivery shall occur, according to the ssssiiiigggg argument, when all the
     I/O operations complete. If ssssiiiigggg is NULL, then no signal delivery occurs
     at the completion of all the items in the list, however notifications for
     each item in the list will happen according to their aaaaiiiiooooccccbbbb---->>>>aaaaiiiioooo____ssssiiiiggggeeeevvvveeeennnntttt
     structures.  If ssssiiiigggg is not NULL then notification will happen according
     to ssssiiiigggg---->>>>ssssiiiiggggeeeevvvv____nnnnoooottttiiiiffffyyyy when all items in the list have completed their I/O
     operations.

     If ssssiiiiggggeeeevvvv____nnnnoooottttiiiiffffyyyy is SSSSIIIIGGGGEEEEVVVV____NNNNOOOONNNNEEEE, then no notification will be posted to the
     calling application.

     If ssssiiiiggggeeeevvvv____nnnnoooottttiiiiffffyyyy is SSSSIIIIGGGGEEEEVVVV____SSSSIIIIGGGGNNNNAAAALLLL, then the signal specified in ssssiiiiggggeeeevvvv____ssssiiiiggggnnnnoooo
     will be sent to the calling process. If SSSSAAAA____SSSSIIIIGGGGIIIINNNNFFFFOOOO is set for the signal
     (see ssssiiiiggggaaaaccccttttiiiioooonnnn((((2222))))) and the signal is in the range of SSSSIIIIGGGGRRRRTTTTMMMMIIIINNNN and
     SSSSIIIIGGGGRRRRTTTTMMMMAAAAXXXX then the signal will be queued to the process and the value in
     ssssiiiiggggeeeevvvv____vvvvaaaalllluuuueeee will be the ssssiiii____vvvvaaaalllluuuueeee in the generated signal.

     If ssssiiiiggggeeeevvvv____nnnnoooottttiiiiffffyyyy is SSSSIIIIGGGGEEEEVVVV____CCCCAAAALLLLLLLLBBBBAAAACCCCKKKK then the function ssssiiiiggggeeeevvvv____ffffuuuunnnncccc will be
     called with ssssiiiiggggeeeevvvv____vvvvaaaalllluuuueeee as the argument. Only one callback will be called
     at a time, however programs should be careful to note that a callback may
     be run in parallel with the calling process.

     If ssssiiiiggggeeeevvvv____nnnnoooottttiiiiffffyyyy is SSSSIIIIGGGGEEEEVVVV____TTTTHHHHRRRREEEEAAAADDDD then the function ssssiiiiggggeeeevvvv____nnnnoooottttiiiiffffyyyy____ffffuuuunnnnccccttttiiiioooonnnn
     will be called by a new thread (see pppptttthhhhrrrreeeeaaaaddddssss((((5555))))) with ssssiiiiggggeeeevvvv____vvvvaaaalllluuuueeee as the
     argument.  This thread is created when the event arrives with the
     attributes specified in ssssiiiiggggeeeevvvv____nnnnoooottttiiiiffffyyyy____aaaattttttttrrrriiiibbbbuuuutttteeeessss except that it is
     automatically detached.  The calling process should ensure there are



                                                                        PPPPaaaaggggeeee 1111






LLLLIIIIOOOO____LLLLIIIISSSSTTTTIIIIOOOO((((3333))))                                                    LLLLIIIIOOOO____LLLLIIIISSSSTTTTIIIIOOOO((((3333))))



     sufficient resources to create the thread.

     The lllliiiisssstttt argument is a pointer to an array of pointers to aaaaiiiiooooccccbbbb
     structures. The array contains nnnneeeennnntttt elements.

     The I/O requests enumerated by list are submitted in an unspecified order
     unless the file was opened with the OOOO____AAAAPPPPPPPPEEEENNNNDDDD in which case the write
     operations will happen in the order that they appear in the list.

     The aaaaiiiioooo____lllliiiioooo____ooooppppccccooooddddeeee field of each aaaaiiiiooooccccbbbb structure specifies the operation
     to be performed. The supported operations are LLLLIIIIOOOO____RRRREEEEAAAADDDD, LLLLIIIIOOOO____WWWWRRRRIIIITTTTEEEE, and
     LLLLIIIIOOOO____NNNNOOOOPPPP.  The LLLLIIIIOOOO____NNNNOOOOPPPP operation causes that list entry to be ignored. If
     the aaaaiiiioooo____lllliiiioooo____ooooppppccccooooddddeeee element is equal to LLLLIIIIOOOO____RRRREEEEAAAADDDD, then an I/O operation is
     submitted as if by a call to aaaaiiiioooo____rrrreeeeaaaadddd(((()))) with the aaaaiiiiooooccccbbbbpppp equal to the
     address of the aiocb ssssttttrrrruuuuccccttttuuuurrrreeee.... IIIIffff tttthhhheeee aaaaiiiioooo____lllliiiioooo____ooooppppccccooooddddeeee element is equal to
     LLLLIIIIOOOO____WWWWRRRRIIIITTTTEEEE, then an I/O operation is submitted as if by a call to
     aaaaiiiioooo____wwwwrrrriiiitttteeee(((()))) with the aaaaiiiiooooccccbbbbpppp equal to the address of the aaaaiiiiooooccccbbbb structure.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     aio_read(3), aio_write(3), aio_error(3), aio_return(3), aio_cancel(3),
     aio_sgi_init(3), aio_hold(3), aio_fsync(3), read(2), lseek(2), close(2),
     _exit(2), exec(2), fork(2), pthreads(5).

DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     If the mmmmooooddddeeee argument has the value LIO_NOWAIT, the lllliiiioooo____lllliiiissssttttiiiioooo(((()))) function
     returns the value 0 to the calling process if the I/O operations are
     successfully queued; otherwise, the function shall return the value -1
     and set _e_r_r_n_o to indicate the error.

     If the mmmmooooddddeeee argument has the value LLLLIIIIOOOO____WWWWAAAAIIIITTTT, the lllliiiioooo____lllliiiissssttttiiiioooo(((())))function
     returns the value 0 to the calling process when all the indicated I/O has
     completed successfully. Otherwise, lllliiiioooo____lllliiiissssttttiiiioooo(((()))) returns -1 to the calling
     process, and sets _e_r_r_n_o to indicate the error.


     In either case, the return value only indicates the success or failure of
     the lllliiiioooo____lllliiiissssttttiiiioooo(((()))) call itself, not the status of the individual I/O
     requests. In some cases one or more of the I/O requests contained in the
     list may fail. Failure of an individual request does not prevent
     completion of any other individual request. To determine the outcome of
     each I/O request, the application shall examine the error status
     associated with each aaaaiiiiooooccccbbbb control block.  The error statuses returned
     are identical to those returned as the result of an aaaaiiiioooo____rrrreeeeaaaadddd((((3333)))) or
     aaaaiiiioooo____wwwwrrrriiiitttteeee((((3333)))) function.

     If any of the following conditions occur, the lllliiiioooo____lllliiiissssttttiiiioooo(((()))) function shall
     return -1 and set _e_r_r_n_o to the corresponding value:

     [EAGAIN]       The resources necessary to queue all the I/O requests were
                    not available. The application may check the error status
                    for each _a_i_o_c_b to determine the individual request(s) that
                    failed.



                                                                        PPPPaaaaggggeeee 2222






LLLLIIIIOOOO____LLLLIIIISSSSTTTTIIIIOOOO((((3333))))                                                    LLLLIIIIOOOO____LLLLIIIISSSSTTTTIIIIOOOO((((3333))))



     [EAGAIN]       The number of entries indicated by nnnneeeennnntttt would cause the
                    system wide limit ____AAAAIIIIOOOO____MMMMAAAAXXXX to be exceeded.

     [EINVAL]       The mmmmooooddddeeee argument is not a proper value. The value of nnnneeeennnntttt
                    was greater than ____AAAAIIIIOOOO____LLLLIIIISSSSTTTTIIIIOOOO____MMMMAAAAXXXX.

     [EINTR]        A signal was delivered while waiting for all I/O requests
                    to complete during a LLLLIIIIOOOO____WWWWAAAAIIIITTTT operation. Note that, since
                    each I/O operation invoked by lllliiiioooo____lllliiiissssttttiiiioooo(((()))) may possibly
                    provoke a signal when it completes, this error return may
                    be caused by the completion of one (or more) of the very
                    I/O operations being awaited. Outstanding I/O requests are
                    not canceled, and the application shall examine each list
                    element to determine whether the request was initiated,
                    canceled or completed.

     [EIO]          One or more of the individual I/O operations failed. The
                    application may check the error status for each aaaaiiiiooooccccbbbb
                    structure to determine the individual request(s) that
                    failed. It is not possible to receive this error return
                    when the mmmmooooddddeeee argument to the lllliiiioooo____lllliiiissssttttiiiioooo(((()))) request was
                    LLLLIIIIOOOO____NNNNOOOOWWWWAAAAIIIITTTT....

     In addition to the errors returned by the lllliiiioooo____lllliiiissssttttiiiioooo(((()))) function, if the
     lllliiiioooo____lllliiiissssttttiiiioooo(((()))) function succeeds or fails with errors of EAGAIN, EINTR or
     ERIO, then some of the I/O operations specified by the list may have been
     initiated. The I/O operation indicated by each list element can encounter
     errors specific to the individual read or write function being performed.
     In this event, the error status for each aaaaiiiiooooccccbbbb control block contains the
     associated error code. The error codes which can be set are the same as
     would be set by a _r_e_a_d(_2) or _w_r_i_t_e(_2) function, with the following error
     codes possible:

     [EAGAIN]       The requested asynchronous I/O operation was not queued
                    due to system resource limitations.

     [ECANCELED]    The requested I/O was canceled before the I/O completed
                    due to an explicit aaaaiiiioooo____ccccaaaannnncccceeeellll((((3333)))) request.

     [EINPROGRESS]  The requested I/O is in progress.















                                                                        PPPPaaaaggggeeee 3333